/**
*  \file sd.h
*
*  \brief Storage Device Abstraction Adapter
*
*  \author Michael J. Hohmann  <michael.hohmann@linde-mh.de>
*
*  This header file provide an interface for generic storage devices.
*/

#ifndef SD_H_INCLUDED
#define SD_H_INCLUDED

/*================================================[ public includes  ]================================================*/
#include "../cfg/prj.h"
#include "../cfg/sd_cfg.h"

/*================================================[ public defines   ]================================================*/

/*================================================[ public datatypes ]================================================*/

/* forward declaration */
struct sd;

/** Read function type. */
typedef RC (*sd_read_function_t) (struct sd *me, void* dest, sd_address_t src, sd_size_t size  );

/** Write function type. */
typedef RC (*sd_write_function_t) (struct sd *me, sd_address_t dest, const void* src, sd_size_t size  );

/** Copy function type.*/
typedef RC (*sd_copy_function_t)(struct sd *me, sd_address_t a, sd_address_t b, sd_size_t size  );

/** Memory set function type.*/
typedef RC (*sd_set_function_t) (struct sd *me, sd_address_t dest, U8 value,  sd_size_t size  );

/** Compare function type.*/
typedef RC (*sd_compare_function_t)(struct sd *me, void* a, sd_address_t b, sd_size_t *psize  );

/** Storage Device Delay Function type. */
typedef RC (*sd_delay_function_t ) (struct sd *me);

/** Storage Device Object
*
*  The class sd contains a set of function pointer that can be inherited into a classes in order
*  to provide an generic interface to access a storage devices.
*
* \attention If this struct is used inside an other struct it has to be the first member of this
*            class !
*/
struct sd
{
   void *object;					/**< Generic Object pointer 							 */
   sd_read_function_t    read;      /**< Read memory object from storage device.             */
   sd_write_function_t   write;     /**< Write memory object into storage device.            */
   sd_copy_function_t    copy;		/**< Copy inside storage device. 						 */
   sd_set_function_t       set;       /**< Fill a memory object of the storage device.		     */
   sd_compare_function_t compare;   /**< Compare two memory objects.                         */
   sd_delay_function_t    delay;     /**< Will be called while waiting for the storage device.*/
};

/*================================================[ public variables ]================================================*/

/*================================================[ public functions ]================================================*/

/** Read from storage device.
*
*  The sd_read() function copies size characters from the object specified by src into the object pointed to by dest.
*
*  \param dev 	Pointer to an existing and initialized storage device object. It is not save to pass NULL.
*  \param dest 	Pointer to the destination of the read operation.
*  \param src 	Address that specify the source object of the read operation.
*  \param size 	Number of bytes to copy.
*
*  \return	RC_SUCCESS if the operation was successful. Error codes are device specific.
*/
STATIC_INLINE RC sd_read( struct sd *dev, void* dest ,sd_address_t src, sd_size_t size )
{
   return dev->read(dev, dest, src, size);
}

/** Write into storage device.
*
*  The sd_write() function copies size characters from the object pointed to by src into the object specified
*  by dest.
*
*  \param dev 	Pointer to an existing and initialized storage device object. It is not save to pass NULL.
*  \param dest 	Address that specify the destination of the write operation.
*  \param src 	Pointer to the source  object of of the read operation.
*  \param size 	Number of bytes to copy.
*
*  \return	RC_SUCCESS if the operation was successful. Error codes are device specific.
*/
STATIC_INLINE RC sd_write( struct sd *dev, sd_address_t dest ,const void* src, sd_size_t size )
{
   return dev->write(dev, dest, src, size);
}

/** Fill memory block in  storage device.
*
*  The sd_set() function copies the passed value into each of the first size characters of the
*  object specified by dest.
*
*  \param dev 	Pointer to an existing and initialized storage device object. It is not save to pass NULL.
*  \param dest 	Address that specify the destination object.
*  \param value Value to set.
*  \param size 	Number of bytes to set.
*
*  \return	RC_SUCCESS if the operation was successful.	Error codes are device specific.
*/
STATIC_INLINE RC sd_set( struct sd *dev, sd_address_t dest, U8 value, sd_size_t size )
{
   return dev->set(dev, dest, value, size);
}

/** Comparison function
*
*  The sd_compare() function compares the first psize characters of the object pointed to by s1 to
*  the first n characters of the object pointed by s2.
*
*  \param dev 	Pointer to an existing and initialized storage device object. It is not save to pass NULL.
*  \param s1 	Pointer to the RAM object.
*  \param s2 	Address of the object located in the storage device.
*  \param psize Pointer to the variable that specify the number of bytes to be compared. The function
*  				will store the number of equal byte in this variable.
*
*  \return	The sd_compare function returns an error code smaller than 0 if an error occur.
*  		   	- 0 if the objects are equal.
*  		   	- 1 if s1 is bigger than s2.
*  		   	- 2 if s2 is smaller than s1.
*/
STATIC_INLINE RC sd_compare( struct sd *dev, void* s1 , sd_address_t s2, sd_size_t *psize )
{
   return dev->compare(dev, s1, s2, psize);
}

/** Copy function
*
*  The sd_copy function copy a memory object with passed size inside the storage device.
*
*  \param dev 	Pointer to an existing and initialized storage device object. It is not save to pass NULL.
*  \param dest 	Address of the destination.
*  \param src 	Address of the source.
*  \param size  Number of byte to copy.
*
*  \return	RC_SUCCESS if the operation was successful. Error codes are device specific.
*/
STATIC_INLINE RC sd_copy( struct sd *dev, sd_address_t dest, sd_address_t src, sd_size_t size )
{
   return dev->copy(dev, dest, src, size);
}

/*====================================================================================================================*/

#endif

/***********************************************************************************************************************
*                             Copyright 2009-2010 Linde Material Handling. All rights reserved.                        *
***********************************************************************************************************************/
